import { Attachment, ToolDefinition, ToolResult, Message, ManualToolHistoryItem, BackendMethodDescriptor, GenerationStatusPayload} from '../types/types';

/**
 * 视图层接口
 * 定义了 Controller 可以操纵 View 进行的所有视觉更新操作
 * 实现了业务逻辑与底层通信协议的解耦
 */

export interface IAgentView {
    // =========================
    // 1. 基础 UI 反馈
    // =========================

    /**
     * 显示全局错误提示（通常是 Toast 或 顶部横幅）
     * 对应 type: 'error'
     */
    showErrorMessage(message: string): Promise<void>;

    /**
     * 通知前端聊天记录已成功清除
     * 对应 type: 'clearSuccess'
     */
    notifyChatCleared(): Promise<void>;

    // =========================
    // 2. AI 对话交互
    // =========================

    /**
     * 显示完整的 AI 回复（适用于 Mock 模式或非流式响应）
     * 对应 type: 'response'
     */
    showAssistantResponse(content: string): Promise<void>;

    /**
     * 发送 AI 流式响应的数据块
     * 对应 type: 'streamChunk'
     * @param messageId 消息ID，用于前端拼接
     * @param chunk 增量文本
     */
    streamAssistantResponse(messageId: string, chunk: string): Promise<void>;

    /**
     * 清除特定的流式消息
     * 场景：AI 原本在说话，突然决定调用工具，需要清除之前的思考文本，转而显示工具调用状态
     * 对应 type: 'clearStreamMessage'
     */
    clearStreamMessage(messageId: string): Promise<void>;

    /**
     * 更新前端可用的工具列表
     * 对应 type: 'toolList'
     */
    updateToolList(tools: ToolDefinition[]): Promise<void>;

    /**
     * 显示工具执行结果
     * 对应 type: 'toolResult'
     */
    showToolResult(result: ToolResult): Promise<void>;

    /**
     * 请求用户确认工具执行
     * 对应 type: 'toolConfirmation'
     * @param toolCall 工具调用详情
     * @param messageId 确认请求的唯一ID
     */
    requestToolConfirmation(toolCall: { id: string; name: string; args: any }, messageId: string): Promise<void>;


    /**
     * 通知前端已选择的文件列表
     * 对应 type: 'filesSelected'
     */
    notifyFilesSelected(files: Attachment[]): Promise<void>;


    /**
     * 恢复完整的会话历史
     * 对应 type: 'restoreHistory'
     */
    restoreHistory(messages: Message[]): Promise<void>;


    //恢复手动工具执行历史 (替代旧的 restoreToolState)
    restoreManualHistory(history: ManualToolHistoryItem[]): Promise<void>;

    /** 更新方法列表 */
    updateMethodList(methods: BackendMethodDescriptor[]): Promise<void>;

    /** 通知项目信息 */
    notifyProjectSelected(path: string): Promise<void>;

    /** 推送生成状态 */
    publishGenerationStatus(status: GenerationStatusPayload): Promise<void>;

    /** 通知生成流程完成 */
    notifyGenerationCompleted(success: boolean): Promise<void>;
}
